Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove superseded XSLT build targets and update README #3985

Merged
merged 3 commits into from
Aug 7, 2024

Conversation

kfranqueiro
Copy link
Contributor

Note: This is intended to land immediately after #3975. I'm sending it up-front so it can get reviewed, since it doesn't require code from the other branch.

WAI site pushes and gh-pages deploys no longer depend on the XSLT build process, and #3975 includes code that will work only with the Eleventy-based build system. To avoid any accidents, this PR removes the parts of the XSLT process that are no longer needed, i.e. anything exclusively related to generating techniques and understanding pages. (Anything related to JSON generation has been left intact, until such time as that is tackled under the new process as well.)

This PR also updates the main README to include a reference to the new build system README, remove references to XML and XSLT, update documentation around term definitions, and add documentation about marking obsolete techniques (which is what #3975 adds).

Additional README fixes:

  • Typos
  • Notation that was being swallowed during markdown parsing (e.g. <version>)
  • Default branch references (updated from master to main)

@kfranqueiro kfranqueiro requested a review from iadawn July 22, 2024 19:48
Copy link

netlify bot commented Jul 22, 2024

Deploy Preview for wcag2 ready!

Name Link
🔨 Latest commit 57f236f
🔍 Latest deploy log https://app.netlify.com/sites/wcag2/deploys/669eb797d13dec00080132e4
😎 Deploy Preview https://deploy-preview-3985--wcag2.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

@w3cbot
Copy link

w3cbot commented Jul 22, 2024

kfranqueiro marked as non substantive for IPR from ash-nazg.

Copy link
Contributor

@bruce-usab bruce-usab left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you Ken. Discussed on facilitators' call 7/29.

iadawn pushed a commit that referenced this pull request Aug 7, 2024
This PR supersedes #3961; it accomplishes the same output, plus resolves
a leftover empty section remaining in that PR.

Related issues: #3651, #3758

## Note to WG

I would appreciate eyes on `obsoleteMessage` wording, seen at the end of
each technique's About box (or at the top of HTML files in this PR) for
restored obsolete techniques:

- Parsing techniques (obsolete in 2.2):
[F70](https://deploy-preview-3975--wcag2.netlify.app/techniques/failures/f70),
[F77](https://deploy-preview-3975--wcag2.netlify.app/techniques/failures/f77),
[G134](https://deploy-preview-3975--wcag2.netlify.app/techniques/general/g134),
[G192](https://deploy-preview-3975--wcag2.netlify.app/techniques/general/g192),
[H74](https://deploy-preview-3975--wcag2.netlify.app/techniques/html/h74),
[H75](https://deploy-preview-3975--wcag2.netlify.app/techniques/html/h75),
[H93](https://deploy-preview-3975--wcag2.netlify.app/techniques/html/h93),
[H94](https://deploy-preview-3975--wcag2.netlify.app/techniques/html/h94)
(all should have the same message)
- Other previously-removed techniques:
[H4](https://deploy-preview-3975--wcag2.netlify.app/techniques/html/h4),
[H35](https://deploy-preview-3975--wcag2.netlify.app/techniques/html/h35),
[H46](https://deploy-preview-3975--wcag2.netlify.app/techniques/html/h46),
[H60](https://deploy-preview-3975--wcag2.netlify.app/techniques/html/h60),
[H73](https://deploy-preview-3975--wcag2.netlify.app/techniques/html/h73),
[H45](https://deploy-preview-3975--wcag2.netlify.app/techniques/html/h45),
[H59](https://deploy-preview-3975--wcag2.netlify.app/techniques/html/h59),
[H70](https://deploy-preview-3975--wcag2.netlify.app/techniques/html/h70),
[SCR37](https://deploy-preview-3975--wcag2.netlify.app/techniques/client-side-script/scr37),
[G187](https://deploy-preview-3975--wcag2.netlify.app/techniques/general/g187),
[F87](https://deploy-preview-3975--wcag2.netlify.app/techniques/failures/f87)
-
[Flash](https://deploy-preview-3975--wcag2.netlify.app/techniques/flash/flash1)
and
[Silverlight](https://deploy-preview-3975--wcag2.netlify.app/techniques/silverlight/sl1)
(Message is implemented centrally for each of these types, inherited
from the XSLT build system)

You don't need to worry about the implementation parts of the PR (unless
you want to); I expect to ask @iadawn to review that part.

## Background

Historically, techniques have been removed from this repository when
they become obsolete. However, they are not removed from the WAI site in
order to avoid link rot. This is not ideal, as it leaves those pages in
isolation with no indication of being obsolete (with the exception of
Flash and Silverlight pages, which had a message added by the build
process).

## Summary

This PR adds support for marking techniques as obsolete via
front-matter. When a technique is marked as obsolete, it has the
following effects:

- Obsolete techniques contain an extra message at the bottom of their
"About this technique" paragraph (roughly following the existing example
from Flash and Silverlight techniques)
- Links to the technique are omitted (e.g. from the [techniques
index](https://deploy-preview-3975--wcag2.netlify.app/techniques/) and
related techniques sections)
- The one exception to this is links from one obsolete technique to
another, in which case the links remain intact, to preserve the current
WAI site behavior of obsolete technique pages remaining effectively
untouched

This PR also adds considerations for WCAG 2.2's obsolete SC, 4.1.1
Parsing:

- Obsolete SC will no longer be referenced within the About this
Technique box regarding applicable SC
- The Related Techniques section in Understanding pages for obsolete SC
is excluded, since those techniques will also no longer reference the SC
- As with the exception to links above, these considerations only apply
to pages that are not also obsolete themselves

## Changes

- Implements 2 data fields for techniques pages:
- `obsoleteSince` - indicates version upon which the technique became
obsolete (in XY notation e.g. `22`)
  - `obsoleteMessage` - Message to display in About this Technique box
- These can be set in front-matter or in directory-level Eleventy data
files (e.g. for Flash and Silverlight)
- Updates some transformation logic to account for new cases where list
items or sections may become empty due to removed links to obsolete
techniques
- Adds back almost all obsolete techniques I could find in git history,
with `obsoleteSince` and `obsoleteMessage` set
- To avoid cruft and confusion, I have intentionally _not_ added back
cross-links between previously-removed techniques, with the exception of
H75 (which will still be relevant in WCAG 2.1, which I am also working
on supporting in the new build system)

## Exclusions

There are 2 techniques I have not restored; if folks have suggestions on
wording for `obsoleteMessage` for them, I can add them:
-
[SCR21](https://www.w3.org/WAI/WCAG22/Techniques/client-side-script/SCR21):
this was [removed](#3652) for
seemingly having more to do with subjective coding preference than
accessibility
- [G222](https://www.w3.org/WAI/WCAG21/Techniques/general/G222): this
only exists in 2.1 docs and probably shouldn't have ever been backported
there, as it pertains to a SC that was initially added in 2.2 (not 2.1!)
then removed before 2.2 was published

## Note: XSLT build system deprecation

This PR introduces front-matter in some HTML files, which the previous
XSLT build system won't know how to handle. Now that we have the
Eleventy build system in use for WAI site updates as well as [gh-pages
deploys](#3955), there should be no
further dependencies on it, and I plan to remove it and think about
updating the main README (update: in #3985).
@kfranqueiro kfranqueiro merged commit 86d3081 into main Aug 7, 2024
5 checks passed
@kfranqueiro kfranqueiro deleted the kgf-remove-superseded-xslt branch August 7, 2024 19:00
kfranqueiro added a commit that referenced this pull request Aug 28, 2024
This does the following:

- Relocates the HTML file for WCAG 2.1's requirements under a
subdirectory, consistent with 2.2's
- This is not currently referenced by any actively-used build/deploy
processes (republishing 2.1 docs is a future task)
- This would technically fix one of the XSLT build targets, which
assumes there's always a version subdirectory; however, that target has
not been recently used and is slated for removal in #3985
- Updates `edDraftURI` in both the 2.1 and 2.2 files, as both referenced
a nonexistent URL
- You may notice that the editors' draft locations are inconsistent
between 2.1 and 2.2; I am not planning on changing that (on the gh-pages
branch) since the current locations are actively linked from each
version of the recommendation, and it seems unlikely that the 2.1 rec
would be updated, which would necessitate a long-standing redirect page.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants